<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Project Darkstar Server Configuration Properties</title>
<link type="text/css" rel="stylesheet" href="config-properties.css">
</head>

<!--

  The properties listed in this file should appear in definition
  list <dl> elements.

  For each property, the name and information about the default should
  appear in a definition term (<dt>) element.  Properties that have a
  default should put the default value in a span element with class
  "default" (<span class="default">VALUE</span>).  Required properties
  should use a span element with class "required"
  (<span class="required"></span>), and properties with no default
  should use class "nodefault" (<span class="nodefault"></span>).

  For example:
  
  <dl>
  <dt>foo.property
  <span class="default">37</span>
  <dd>Controls how big foo is.
  </dl>

  Or:

  <dl>
  <dt>goo.property
  <span class="required"></span>
  <dd>Controls how big goo is.
  </dl>

  Since this file will be included in the public application
  documentation, make sure to not refer to classes that will not be
  documented there.

-->

<body>

<h1>Project Darkstar Server Configuration Properties</h1>

This page documents the configuration properties supported by version ${pom.version}
of the Project Darkstar Server.  Configuration properties may be specified by
system properties (using 
<code>-D</code><i>property</i><code>=</code><i>value</i>)
or in the application properties file named on the command line. Any changes to
configuration properties from previous releases will be noted in the 
release documentation.

<p>
By default, the Project Darkstar Server consists of a single node, as described
in <a href="#SingleNodeConfig">Configuring a Single Node System</a>.
Alternatively, multiple nodes can be configured to work together, as
described in <a href="#MultiNodeConfig">Configuring a Multi-Node System</a>.
<p>
The type of node being configured is specified by the following property:
<dl>
<dt><a name="node.type">com.sun.sgs.node.type</a>
<span class="default">singleNode</span>
<dd> Indicates which type of node is being started, and has valid settings of
<ul>
    <li><code>singleNode</code>
    <li><code>coreServerNode</code>
    <li><code>appNode</code>
</ul>
</dl>

<p>
For example configuration files of the different node types, see the
<a href="single-node.properties">single-node.properties</a>,
<a href="core-server.properties">core-server.properties</a>, and
<a href="app-node.properties">app-node.properties</a> files.


<a name="SingleNodeConfig"></a>
<h2>Configuring a Single Node System</h2>

A single node systems consists of a Darkstar Server running in a single
Java Virtual Machine.  This is the default server type for Project Darkstar.
Note that the <a href="#RequiredProperties">Required Properties</a>
will also need to be specified.

<a name="MultiNodeConfig"></a>
<h2>Configuring a Multi-Node System</h2>
The Project Darkstar Server can be run on multiple nodes configured to work 
together in a cluster.  This multi-node configuration requires a special 
<i>core server node</i> to run critical Project Darkstar operations, with the 
remaining nodes, the <i>application nodes</i>, cooperating to run the 
application.  Application nodes can be dynamically added or removed from the
cluster.
<p>
The core server node <b>must</b> be running before starting the application 
nodes.
<p>
Properties in this section specify which node is the core server node, which
are the application nodes, and how the application nodes discover the
core node.  Note that some <a href="#RequiredProperties">Required Properties</a>
will also need to be specified.

<h3>Core Server Node Properties</h3>
These properties control the configuration of the Project Darkstar core
server node if a multi-node configuration is being used. Currently, there is 
only one core server per cluster of Project Darkstar nodes; if multiple core 
servers are started, then each will be associated with its own independent 
Project Darkstar cluster.
<p>
The <a href="#node.type">node.type</a> property must be set to 
<code>coreServerNode</code> to start the core server.

<h3>Application Node Properties</h3>
These properties control the configuration of the Project Darkstar application
nodes if a multi-node configuration is being used.
<p>
The <a href="#node.type">node.type</a> property must be set to 
<code>appNode</code> to start an application node.

<dl>
<dt><a name="com.sun.sgs.server.host">com.sun.sgs.server.host</a>
<span class="required"> for application nodes</span>
<dd> The name of the host the core Project Darkstar Server node is running on. 

</dl>

<a name="RequiredProperties"></a>
<h2>Required Properties</h2>

These properties are required for some or all node types.

<dl>

<dt><a name="com.sun.sgs.app.name">com.sun.sgs.app.name</a>
<span class="required"></span>
<dd>The name of the application.  If running in a multi-node configuration, 
this name must be the same for each node.

<dt><a name="app.root">com.sun.sgs.app.root</a>
<span class="required"></span>
<dd>The root directory for the application, which specifies local file system 
space available for Project Darkstar use.

<dt><a name="app.listener">com.sun.sgs.app.listener</a>
<span class="required"> for application and single nodes</span>
<dd>The <a href="../AppListener.html"><code>AppListener</code></a> for
  the application, specified as a fully qualified class name.

<dt><a name="com.sun.sgs.app.port">com.sun.sgs.app.port</a>
<span class="required"> for application and single nodes</span>
<dd>The TCP port on which to listen for client connections.

</dl>

<a name="CommonProperties"></a>
<h2>Other Common Properties</h2>

These properties control various general facilities in the Project Darkstar
Server, and can be used in any node configuration unless otherwise specified.

<a name="CoreServerPorts"></a>
<h3>Core Server Port Properties</h3>
These properties can be used by either core server or application nodes in
a multi-node configuration.  The core server node may be configured to specify 
ports to be used on the core server machine.  If these properties are used, 
they must be set to the same value on each application node.

<dl>
<dt>com.sun.sgs.impl.service.data.store.net.server.port
<span class="default">44530</span>
<dd>The TCP port for the data service's shared network server.  
<dt>com.sun.sgs.impl.service.watchdog.server.port
<span class="default">44533</span>
<dd>The TCP port for the watchdog service's internal server.
<dt>com.sun.sgs.impl.service.nodemap.server.port
<span class="default">44535</span>
<dd>The TCP port for the node mapping service's internal server.
</dl>

<a name="DataService"></a>
<h3>DataService Properties</h3>

These properties control the implementation of the
<code>DataService</code>.

<a name="DataStore"></a>
<h4>DataStore Properties</h4>

These properties are the subset of the properties supported by
the <code>DataService</code> that control the implementation of the
underlying <code>DataStore</code>.  Setting these properties has no
effect on application nodes.

<dl>

<dt>com.sun.sgs.impl.service.data.store.DataStoreImpl.directory
<span class="default"><i>${com.sun.sgs.app.root}</i>/dsdb</span>
<dd>The directory in which to store database files.  Each single node or
  core server node requires its own, unique directory.

</dl>

<a name="Db"></a>
<h4>Database Properties</h4>

These properties are the subset of the properties supported by
the <code>DataService</code> that select the implementation of the
underlying database.  Setting these properties has no effect on
application nodes.
<dl>

<a name="com.sun.sgs.impl.service.data.store.db.environment.class"></a>
<dt>com.sun.sgs.impl.service.data.store.db.environment.class
<span class="default">
  com.sun.sgs.impl.service.data.store.db.bdb.BdbEnvironment
</span>
<dd>The name of the class that implements the underlying database.  The
  default value selects a database implementation based
  on <a href="http://www.oracle.com/database/berkeley-db/db/index.html">
  Berkeley DB</a>.  Specifying
  <code>com.sun.sgs.impl.service.data.store.db.je.JeEnvironment</code>
  selects a database implementation based on
  <a href="http://www.oracle.com/database/berkeley-db/je/index.html">
  Berkeley DB Java Edition</a>.  Other values should specify the fully
  qualified name of a class that satisfies the requirements specified by
  the <code>
  com.sun.sgs.impl.service.data.store.db.DbEnvironmentFactory.getEnvironment
  </code> method. <p>

  Note that persistent data created using Berkeley DB is incompatible
  with data created using Berkeley DB Java edition
</dl>

<a name="Bdb"></a>
<h4>Berkeley DB Properties</h4>

These properties are the subset of the properties supported by
the <code>DataService</code> that control the behavior of the Berkeley
DB database, when it has been specified as the implementation of the
underlying database using the
<a href="#com.sun.sgs.impl.service.data.store.db.environment.class"><code>
com.sun.sgs.impl.service.data.store.db.environment.class</code></a>
property. Setting these properties has no effect on application nodes.
<dl>

<dt>com.sun.sgs.impl.service.data.store.db.bdb.cache.size
<span class="default">128000000</span>
<dd>The size in bytes of the Berkeley DB cache.  The value must not be
  less than <code>20000</code>.  Using a cache that is too small
  can introduce a significant reduction in performance.

<dt>com.sun.sgs.impl.service.data.store.db.bdb.remove.logs
<span class="default">false</span>
<dd>Whether to automatically remove database log files that are no
  longer needed.  Note that automatic log file removal is likely to make
  catastrophic recovery of the database impossible, because log files
  that may be needed will not have been backed up.

</dl>

<a name="Watchdog"></a>
<h3>Watchdog Service Properties</h3>
These properties control the implementation of the <code>WatchdogService</code>.
Setting these properties has no effect on application nodes.
<dl>

<dt>com.sun.sgs.impl.service.watchdog.server.renew.interval
<span class="default">1000 (for a multi-node configuration) or
Integer.MAX_VALUE (for a single node configuration) </span>
<dd>The time interval, in milliseconds, in which application nodes must
  contact the watchdog service's internal server in order to be considered
  alive. This time interval is sent to each application node during start up, 
  when the application node registers with the watchdog's internal server. The 
  interval must be greater than or equal to <code>100</code> milliseconds.
  Using a renew interval that is too small may cause some application nodes to
  be considered failed by the <code>WatchdogService</code> when they are very
  busy. Using an interval that is too large will increase the amount of time the 
  system takes to respond to failed nodes.

</dl>

<a name="ClientSessionService"></a>
<h3>ClientSessionService Properties</h3>
These properties control the implementation of the
<code>ClientSessionService</code>.
<dl>

<dt>com.sun.sgs.impl.service.session.disconnect.delay
<span class="default">1000</span>
<dd>The time, in milliseconds, in which a disconnecting client is allowed to close a
connection before it is closed by the server. The delay must be greater than or
equal to <code>200</code> milliseconds.
</dl>

<a name="System"></a>
<h3>System Properties</h3>

These properties control the implementation of the core components of the 
system including identity management, profiling, and task scheduling.

<dl>
<dt>com.sun.sgs.app.authenticators
<span class="default">com.sun.sgs.impl.auth.NullAuthenticator</span>
<dd>A colon separated list of <a href="../../auth/IdentityAuthenticator.html">
  <code>IdentityAuthenticator</code>s</a> to use for the application. The
  order defines the precedence when authenticating an identity. The default
  authenticator simply accepts any name-password pair.
    
<dt>com.sun.sgs.impl.kernel.profile.level
<span class="default">min</span>
<dd>The profiling level. Valid levels are
<ul>
    <li><code>min</code> - minimal profiling data is collected. 
    <li><code>medium</code>  - more data is collected, but is still appropriate 
                             for monitoring a production system.
    <li><code>max</code> - all available profiling data is collected.  This 
                         level may only be appropriate for debugging systems in
                         development.
</ul>

<dt>com.sun.sgs.impl.kernel.profile.listeners
<span class="nodefault"/>
<dd>A colon separated list of profile listeners, which consume profile output.
  To configure the available listeners, see the individual class javadoc for 
  profile listener implementations.

<dt>com.sun.sgs.impl.kernel.transaction.threads
<span class="default">4</span>
<dd>The number of initial threads used to process transactional tasks, such as 
  those started through the 
  <a href="../TaskManager.html"><code>TaskManager</code></a>.

<dt>com.sun.sgs.impl.kernel.task.threads
<span class="default">4</span>
<dd>The number of initial threads used to process non-transactional tasks.

</dl>

<a name="DebugProperties"></a>
<h2>Debug and Test Properties</h2>

These properties are most useful for debugging and testing, and are not
typically useful for production deployments.

<dl>
<dt><a name="com.sun.sgs.txn.timeout">com.sun.sgs.txn.timeout</a>
<span class="default">100</span>
<dd>The maximum amount of time in milliseconds that a transaction will
  be permitted to run before it is a candidate for being aborted.  Increasing
  this timeout is useful when attaching a debugger to a node, but can 
  increase game latency.

</dl>
<hr>
<font size="-1">
  Copyright &copy; 2007-2008 Sun Microsystems, Inc. All rights reserved
</font>

</body>
</html>
